<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><title>Resource Query Language</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="Resource Query Language">
<meta name="keywords" content="resource, query">
<meta name="generator" content="xml2rfc v1.35 (http://xml.resource.org/)">
<style type='text/css'><!--
        body {
                font-family: verdana, charcoal, helvetica, arial, sans-serif;
                font-size: small; color: #000; background-color: #FFF;
                margin: 2em;
        }
        h1, h2, h3, h4, h5, h6 {
                font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif;
                font-weight: bold; font-style: normal;
        }
        h1 { color: #900; background-color: transparent; text-align: right; }
        h3 { color: #333; background-color: transparent; }

        td.RFCbug {
                font-size: x-small; text-decoration: none;
                width: 30px; height: 30px; padding-top: 2px;
                text-align: justify; vertical-align: middle;
                background-color: #000;
        }
        td.RFCbug span.RFC {
                font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
                font-weight: bold; color: #666;
        }
        td.RFCbug span.hotText {
                font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif;
                font-weight: normal; text-align: center; color: #FFF;
        }

        table.TOCbug { width: 30px; height: 15px; }
        td.TOCbug {
                text-align: center; width: 30px; height: 15px;
                color: #FFF; background-color: #900;
        }
        td.TOCbug a {
                font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif;
                font-weight: bold; font-size: x-small; text-decoration: none;
                color: #FFF; background-color: transparent;
        }

        td.header {
                font-family: arial, helvetica, sans-serif; font-size: x-small;
                vertical-align: top; width: 33%;
                color: #FFF; background-color: #666;
        }
        td.author { font-weight: bold; font-size: x-small; margin-left: 4em; }
        td.author-text { font-size: x-small; }

        /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
        a.info {
                /* This is the key. */
                position: relative;
                z-index: 24;
                text-decoration: none;
        }
        a.info:hover {
                z-index: 25;
                color: #FFF; background-color: #900;
        }
        a.info span { display: none; }
        a.info:hover span.info {
                /* The span will display just on :hover state. */
                display: block;
                position: absolute;
                font-size: smaller;
                top: 2em; left: -5em; width: 15em;
                padding: 2px; border: 1px solid #333;
                color: #900; background-color: #EEE;
                text-align: left;
        }

        a { font-weight: bold; }
        a:link    { color: #900; background-color: transparent; }
        a:visited { color: #633; background-color: transparent; }
        a:active  { color: #633; background-color: transparent; }

        p { margin-left: 2em; margin-right: 2em; }
        p.copyright { font-size: x-small; }
        p.toc { font-size: small; font-weight: bold; margin-left: 3em; }
        table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; }
        td.toc { font-size: small; font-weight: bold; vertical-align: text-top; }

        ol.text { margin-left: 2em; margin-right: 2em; }
        ul.text { margin-left: 2em; margin-right: 2em; }
        li      { margin-left: 3em; }

        /* RFC-2629 <spanx>s and <artwork>s. */
        em     { font-style: italic; }
        strong { font-weight: bold; }
        dfn    { font-weight: bold; font-style: normal; }
        cite   { font-weight: normal; font-style: normal; }
        tt     { color: #036; }
        tt, pre, pre dfn, pre em, pre cite, pre span {
                font-family: "Courier New", Courier, monospace; font-size: small;
        }
        pre {
                text-align: left; padding: 4px;
                color: #000; background-color: #CCC;
        }
        pre dfn  { color: #900; }
        pre em   { color: #66F; background-color: #FFC; font-weight: normal; }
        pre .key { color: #33C; font-weight: bold; }
        pre .id  { color: #900; }
        pre .str { color: #000; background-color: #CFF; }
        pre .val { color: #066; }
        pre .rep { color: #909; }
        pre .oth { color: #000; background-color: #FCF; }
        pre .err { background-color: #FCC; }

        /* RFC-2629 <texttable>s. */
        table.all, table.full, table.headers, table.none {
                font-size: small; text-align: center; border-width: 2px;
                vertical-align: top; border-collapse: collapse;
        }
        table.all, table.full { border-style: solid; border-color: black; }
        table.headers, table.none { border-style: none; }
        th {
                font-weight: bold; border-color: black;
                border-width: 2px 2px 3px 2px;
        }
        table.all th, table.full th { border-style: solid; }
        table.headers th { border-style: none none solid none; }
        table.none th { border-style: none; }
        table.all td {
                border-style: solid; border-color: #333;
                border-width: 1px 2px;
        }
        table.full td, table.headers td, table.none td { border-style: none; }

        hr { height: 1px; }
        hr.insert {
                width: 80%; border-style: none; border-width: 0;
                color: #CCC; background-color: #CCC;
        }
--></style>
</head>
<body>
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1">
<tr><td class="header">Internet Engineering Task Force</td><td class="header">K. Zyp, Ed.</td></tr>
<tr><td class="header">Internet-Draft</td><td class="header">SitePen (USA)</td></tr>
<tr><td class="header">Intended status: Informational</td><td class="header">June 30, 2010</td></tr>
<tr><td class="header">Expires: January 1, 2011</td><td class="header">&nbsp;</td></tr>
</table></td></tr></table>
<h1><br />Resource Query Language<br />draft-zyp-rql-00</h1>

<h3>Abstract</h3>

<p>Resource Query Languages (RQL) defines a syntactically simple query language 
      for querying and retrieving resources. RQL is designed to be URI friendly, 
      particularly as a query component of a URI, and highly extensible. RQL is a superset
      of HTML's URL encoding of form values, and a superset of Feed Item Query Language (FIQL).
      RQL basically consists of a set of nestable named operators which each have a set of 
      arguments and operate on a collection of resources. An example of an RQL for finding
      resources with a category of "toy" and sorted by price in ascending order:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

category=toy&amp;sort(+price)
</pre></div><p>

      
</p>
<h3>Status of This Memo</h3>
<p>
This Internet-Draft is submitted  in full
conformance with the provisions of BCP&nbsp;78 and BCP&nbsp;79.</p>
<p>
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF).  Note that other groups may also distribute
working documents as Internet-Drafts.  The list of current
Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p>
<p>
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any time.
It is inappropriate to use Internet-Drafts as reference material or to cite
them other than as &ldquo;work in progress.&rdquo;</p>
<p>
This Internet-Draft will expire on January 1, 2011.</p>

<h3>Copyright Notice</h3>
<p>
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors.  All rights reserved.</p>
<p>
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document.  Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.</p>
<a name="toc"></a><br /><hr />
<h3>Table of Contents</h3>
<p class="toc">
<a href="#anchor1">1.</a>&nbsp;
Introduction<br />
<a href="#anchor2">2.</a>&nbsp;
Conventions<br />
<a href="#anchor3">3.</a>&nbsp;
Overview<br />
<a href="#anchor4">4.</a>&nbsp;
Operators<br />
<a href="#anchor5">5.</a>&nbsp;
Values<br />
<a href="#anchor6">6.</a>&nbsp;
Arrays<br />
<a href="#anchor7">7.</a>&nbsp;
Nested Operators<br />
<a href="#anchor8">8.</a>&nbsp;
Defined Operators<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor9">8.1.</a>&nbsp;
sort<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor10">8.2.</a>&nbsp;
select<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor11">8.3.</a>&nbsp;
aggregate<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor12">8.4.</a>&nbsp;
distinct<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor13">8.5.</a>&nbsp;
in<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor14">8.6.</a>&nbsp;
contains<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor15">8.7.</a>&nbsp;
limit<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor16">8.8.</a>&nbsp;
and<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor17">8.9.</a>&nbsp;
or<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor18">8.10.</a>&nbsp;
eq<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor19">8.11.</a>&nbsp;
lt<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor20">8.12.</a>&nbsp;
le<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor21">8.13.</a>&nbsp;
gt<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor22">8.14.</a>&nbsp;
ge<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor23">8.15.</a>&nbsp;
ne<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor24">8.16.</a>&nbsp;
sum<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor25">8.17.</a>&nbsp;
mean<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor26">8.18.</a>&nbsp;
max<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor27">8.19.</a>&nbsp;
min<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#anchor28">8.20.</a>&nbsp;
recurse<br />
<a href="#anchor29">9.</a>&nbsp;
Comparison Syntax<br />
<a href="#anchor30">10.</a>&nbsp;
Typed Values<br />
<a href="#anchor31">11.</a>&nbsp;
ABNF for RQL<br />
<a href="#anchor32">12.</a>&nbsp;
HTTP<br />
<a href="#anchor33">13.</a>&nbsp;
IANA Considerations<br />
<a href="#rfc.references1">14.</a>&nbsp;
References<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#rfc.references1">14.1.</a>&nbsp;
Normative References<br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#rfc.references2">14.2.</a>&nbsp;
Informative References<br />
<a href="#anchor36">Appendix&nbsp;A.</a>&nbsp;
Change Log <br />
<a href="#anchor37">Appendix&nbsp;B.</a>&nbsp;
Open Issues<br />
</p>
<br clear="all" />

<a name="anchor1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.1"></a><h3>1.&nbsp;
Introduction</h3>

<p>Resource Query Languages (RQL) defines a syntactically simple query language 
      for querying and retrieving resources. RQL is designed to be URI friendly, 
      particularly as a query component of a URI, and highly extensible. RQL is a superset
      of HTML's URL encoding of form values, and a superset of Feed Item Query Language (FIQL).

</p>
<a name="anchor2"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.2"></a><h3>2.&nbsp;
Conventions</h3>

<p>The key words "MUST", "MUST
      NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
      "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
      interpreted as described in RFC 2119.
</p>
<a name="anchor3"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.3"></a><h3>3.&nbsp;
Overview</h3>

<p>RQL consists of a set of nestable named operators which each have a set of 
      arguments. RQL is designed to be applied to a collection of resources. Each top-level 
      operator defines a constraint or modification to the result of the query from the base 
      collection of resources. Nested operators provide constraint information for the operators within which they are embedded. 
      
</p>
<a name="anchor4"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.4"></a><h3>4.&nbsp;
Operators</h3>

<p>
      An operator consists of an operator name followed by a list of comma-delimited arguments within paranthesis:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

name(args,...)
</pre></div><p>

      Each argument may be a value (a string of unreserved or URL-encoded characters), an array, or another operator. The name of the operator indicates the type of action the operator will perform on the collection, using the given arguments. This document defines the semantics of a set of operators, but the query language can be extended with additional operators.
</p>
<p>      
      A simple RQL query with a single operator that indicates a search for any 
      resources with a property of "foo" that has value of 3 could be written:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

eq(foo,3)
</pre></div><p>

      
</p>
<a name="anchor5"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.5"></a><h3>5.&nbsp;
Values</h3>

<p>
	Simple values are simply URL-encoded sequences of characters. Unreserved characters do not need to be encoded, other characters should be encoding using standard URL encoding. Simple values can be decoded to determine the intended string of characters. Values can also include arrays or typed values. These are described in the "Typed Values" and "Arrays" section below.
      
</p>
<a name="anchor6"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.6"></a><h3>6.&nbsp;
Arrays</h3>

<p>
      One of the allowable arguments for operators is an array. An array is paranthesis-enclosed comma-delimited set of items. Each item in the array can be a value or an operator. A query that finds all the resources where the category can be "toy" or "food" could be written with an array argument:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

in(category,(toy,food))
</pre></div><p>

      
      
</p>
<a name="anchor7"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.7"></a><h3>7.&nbsp;
Nested Operators</h3>

<p>
      Operators may be nested. For example, a set of operators can be used as the arguments for the "or" operator. Another query that finds all the resources where the category can be "toy" or "food" could be written with nested "eq" operators within an "or" operator:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

or(eq(category,toy),eq(category,food))
</pre></div><p>

      
</p>
<a name="anchor8"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8"></a><h3>8.&nbsp;
Defined Operators</h3>

<p>
      RQL defines the following semantics for these operators:
     
<a name="anchor9"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.1"></a><h3>8.1.&nbsp;
sort</h3>

<p>sort(&lt;+|->&lt;property) - Sorts the returned query result by the given property. The order of sort is specified by the prefix (+ for ascending, - for descending) to property.
      To sort by foo in ascending order:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

sort(+foo)
</pre></div><p>

      One can also do multiple property sorts. To sort by price in ascending order and rating in descending order:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

sort(+price,-rating)
</pre></div><p>

      
</p>
     
<a name="anchor10"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.2"></a><h3>8.2.&nbsp;
select</h3>

<p>select(&lt;property>) - Returns a query result where each item is value of the property specified by the argument
</p>
<p>select(&lt;property>,&lt;property>,...) - Trims each object down to the set of properties defined in the arguments
</p>
     
<a name="anchor11"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.3"></a><h3>8.3.&nbsp;
aggregate</h3>

<p>aggregate(&lt;property|operator>,...) - The aggregate function can be used for aggregation, it aggregates the result set, grouping by objects that are distinct for the provided properties, and then reduces the remaining other property values using the provided operator. To calculate the sum of sales for each department:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

aggregate(departmentId,sum(sales))
</pre></div><p>


</p>
     
<a name="anchor12"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.4"></a><h3>8.4.&nbsp;
distinct</h3>

<p>distinct() - Returns a result set with duplicates removed
</p>
     
<a name="anchor13"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.5"></a><h3>8.5.&nbsp;
in</h3>

<p>in(&lt;property>,&lt;array-of-values>) - Filters for objects where the specified property's value is in the provided array
</p>
     
<a name="anchor14"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.6"></a><h3>8.6.&nbsp;
contains</h3>

<p>contains(&lt;property>,&lt;value | array-of-values>) - Filters for objects where the specified property's value is an array and the array contains the provided value or contains a value in the provided array
</p>
     
<a name="anchor15"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.7"></a><h3>8.7.&nbsp;
limit</h3>

<p>limit(start,count) - Returns a limited range of records from the result set. The first parameter indicates the starting offset and the second parameter indicates the number of records to return.
</p>
     
<a name="anchor16"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.8"></a><h3>8.8.&nbsp;
and</h3>

<p>and(&lt;query>,&lt;query>,...) - Returns a query result set applying all the given operators to constrain the query
</p>
     
<a name="anchor17"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.9"></a><h3>8.9.&nbsp;
or</h3>

<p>or(&lt;query>,&lt;query>,...) - Returns a union result set of the given operators
</p>
     
<a name="anchor18"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
eq</h3>

<p>eq(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is equal to the provided value
</p>
     
<a name="anchor19"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.11"></a><h3>8.11.&nbsp;
lt</h3>

<p>lt(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is less than the provided value
</p>
     
<a name="anchor20"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.12"></a><h3>8.12.&nbsp;
le</h3>

<p>le(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is less than or equal to the provided value
</p>
     
<a name="anchor21"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.13"></a><h3>8.13.&nbsp;
gt</h3>

<p>gt(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is greater than the provided value
</p>
     
<a name="anchor22"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.14"></a><h3>8.14.&nbsp;
ge</h3>

<p>ge(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is greater than or equal to the provided value
</p>
     
<a name="anchor23"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.15"></a><h3>8.15.&nbsp;
ne</h3>

<p>ne(&lt;property>,&lt;value>) - Filters for objects where the specified property's value is not equal to the provided value
</p>
     
<a name="anchor24"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.16"></a><h3>8.16.&nbsp;
sum</h3>

<p>sum(&lt;property?>) - Finds the sum of every value in the array or if the property argument is provided, returns the sum of the value of property for every object in the array
</p>
     
<a name="anchor25"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.17"></a><h3>8.17.&nbsp;
mean</h3>

<p>mean(&lt;property?>) - Finds the mean of every value in the array or if the property argument is provided, returns the mean of the value of property for every object in the array
</p>
     
<a name="anchor26"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.18"></a><h3>8.18.&nbsp;
max</h3>

<p>max(&lt;property?>) - Finds the maximum of every value in the array or if the property argument is provided, returns the maximum of the value of property for every object in the array
</p>
     
<a name="anchor27"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.19"></a><h3>8.19.&nbsp;
min</h3>

<p>min(&lt;property?>) - Finds the minimum of every value in the array or if the property argument is provided, returns the minimum of the value of property for every object in the array
</p>
     
<a name="anchor28"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.8.20"></a><h3>8.20.&nbsp;
recurse</h3>

<p>recurse(&lt;property?>) - Recursively searches, looking in children of the object as objects in arrays in the given property value
</p>
      

<a name="anchor29"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.9"></a><h3>9.&nbsp;
Comparison Syntax</h3>

<p>
    RQL provides a semantically equivelant syntactic alternate to operator syntax with comparison syntax. A comparison operator may
    be written in the form:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

name=value
</pre></div><p>

As shorthand for:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

eq(name,value)
</pre></div><p>

RQL also supports provides sugar for the "and" operator with ampersand delimited operators. The following form:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

operator&amp;operator
</pre></div><p>

As shorthand for:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

and(operator,operator)
</pre></div><p>

With these transformations, one can write queries of the form:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

foo=3&amp;bar=text
</pre></div><p>

This makes the HTML's form url encoding of name value pairs a proper query within RQL.
</p>
<p>
Ampersand delimited operators may be grouped by placing them within paranthesis. Top level queries themselves are considered to be implicitly a part of an "and" operator group, and therefore the top level ampersand delimited operators do not need to be enclosed with paranthesis, but "and" groups used within other operators do need to be enclosed in paranthesis.
</p>
<p>
Pipe delimited operators may also be placed within paranthesis-enclosed groups as shorthand for the "or" operator. One can write a query:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

foo=3&amp;(bar=text|bar=string)
</pre></div><p>

Also, Feed Item Query Language is a subset of RQL valid. RQL supports named comparisons as shorthand for operators as well. The following form is a named comparison:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

name=comparator=value
</pre></div><p>

Which is shorthand for:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

comparator(name,value)
</pre></div><p>

For example, to find resources with a "price" less than 10:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

price=lt=10
</pre></div><p>


</p>
<a name="anchor30"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.10"></a><h3>10.&nbsp;
Typed Values</h3>

<p>
Basic values in RQL are simply a string of characters and it is up to the recipient of a query to determine how these characters should be interpreted and if they should be coerced to alternate data types understood by the language or database processing the query. However, RQL supports typed values to provide hints to the recipient of the intended data type of the value. The syntax of a typed value is:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

type:value
</pre></div><p>

RQL suggests the following types to be supported:
</p>
<blockquote class="text">
<p>string - Indicates the value string should not be coerced, it should remain a string.
</p>
<p>number - Indicates the value string should be coerced to a number.
</p>
<p>boolean - Indicates the value string should be coerced to a boolean. A value of "true" should indicate true and a value of "false" should indicate false.
</p>
<p>epoch - Indicates the value string should be treated as the milliseconds since the epoch and coerced to a date.
</p>
</blockquote><p>
For example, to query for resources where foo explicitly equals the number 4:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

foo=number:4
</pre></div><p>



</p>
<a name="anchor31"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.11"></a><h3>11.&nbsp;
ABNF for RQL</h3>

<p>
The following is the collected ABNF for RQL:
      </p>
<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>

query = and

and = operator *( "&amp;" operator )
operator = comparison / call-operator / group
call-operator = name "(" [ argument *( "," argument ) ] ")"
argument = call-operator / value
value = *nchar / typed-value / array
typed-value = 1*nchar ":" *nchar
array = "(" [ value *( "," value ) ] ")"
name = *nchar

comparison = name ( "=" [ name "=" ] ) value
group = "(" ( and / or ) ")"
or = operator *( "|" operator )

nchar = unreserved / pct-encoded / "*" / "+"
pct-encoded   = "%" HEXDIG HEXDIG
unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"

</pre></div><p>



</p>
<a name="anchor32"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.12"></a><h3>12.&nbsp;
HTTP</h3>

<p>
If RQL is used as for to define queries in HTTP URLs, there are several considerations. First, servers that allow publicly initiated requests should enforce proper security measures to protect against excessive resource consumption. Many operators may be understood
by the server, but not efficiently executable and servers can therefore reject such queries. Rejections may be indicated by a 403 Forbidden status code response, or if authentication may provide the authorization necessary to perform the query, a 401 Unauthorized status code can be sent.

</p>
<p>
If the query is not syntactically valid, (does not follow the RQL grammar), the server may return a status code of 400 Bad Request. If the query is syntactically valid, but the operator name is not known, the server may also return a status code of 400 Bad Request.

</p>
<a name="anchor33"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.13"></a><h3>13.&nbsp;
IANA Considerations</h3>

<p>
   The proposed MIME media type for Resource Query Language is application/rql

</p>
<p>
   Type name: application

</p>
<p>
   Subtype name: rql

</p>
<p>
   Required parameters: none
   
</p>
<p>
   Optional parameters: none
   
</p>
<a name="rfc.references"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.14"></a><h3>14.&nbsp;
References</h3>

<a name="rfc.references1"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<h3>14.1.&nbsp;Normative References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
<td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,&rdquo; BCP&nbsp;14, RFC&nbsp;2119, March&nbsp;1997 (<a href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="RFC3986">[RFC3986]</a></td>
<td class="author-text"><a href="mailto:timbl@w3.org">Berners-Lee, T.</a>, <a href="mailto:fielding@gbiv.com">Fielding, R.</a>, and <a href="mailto:LMM@acm.org">L. Masinter</a>, &ldquo;<a href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</a>,&rdquo; STD&nbsp;66, RFC&nbsp;3986, January&nbsp;2005 (<a href="http://www.rfc-editor.org/rfc/rfc3986.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc3986.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc3986.xml">XML</a>).</td></tr>
</table>

<a name="rfc.references2"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<h3>14.2.&nbsp;Informative References</h3>
<table width="99%" border="0">
<tr><td class="author-text" valign="top"><a name="W3C.REC-html401-19991224">[W3C.REC-html401-19991224]</a></td>
<td class="author-text">Hors, A., Raggett, D., and I. Jacobs, &ldquo;<a href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML 4.01 Specification</a>,&rdquo; World Wide Web Consortium Recommendation&nbsp;REC-html401-19991224, December&nbsp;1999 (<a href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML</a>).</td></tr>
<tr><td class="author-text" valign="top"><a name="I-D.nottingham-atompub-fiql">[I-D.nottingham-atompub-fiql]</a></td>
<td class="author-text">Nottingham, M., &ldquo;<a href="http://www.ietf.org/internet-drafts/draft-nottingham-atompub-fiql-00.txt">FIQL: The Feed Item Query Language</a>,&rdquo; draft-nottingham-atompub-fiql-00 (work in progress), December&nbsp;2007 (<a href="http://www.ietf.org/internet-drafts/draft-nottingham-atompub-fiql-00.txt">TXT</a>).</td></tr>
</table>

<a name="anchor36"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.A"></a><h3>Appendix A.&nbsp;
Change Log </h3>

<p>-00
</p>
<p>
            </p>
<ul class="text">
<li>Initial draft
</li>
</ul><p>
          
</p>
<a name="anchor37"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<a name="rfc.section.B"></a><h3>Appendix B.&nbsp;
Open Issues</h3>

<a name="rfc.authors"></a><br /><hr />
<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
<h3>Author's Address</h3>
<table width="99%" border="0" cellpadding="0" cellspacing="0">
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">Kris Zyp (editor)</td></tr>
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">SitePen (USA)</td></tr>
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">530 Lytton Avenue</td></tr>
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">Palo Alto, CA 94301</td></tr>
<tr><td class="author-text">&nbsp;</td>
<td class="author-text">USA</td></tr>
<tr><td class="author" align="right">Phone:&nbsp;</td>
<td class="author-text">+1 650 968 8787</td></tr>
<tr><td class="author" align="right">EMail:&nbsp;</td>
<td class="author-text"><a href="mailto:kris@sitepen.com">kris@sitepen.com</a></td></tr>
</table>
</body></html>

